7.1 Property Lists

These functions augment the standard Emacs Lisp functions get and put for operating on properties attached to symbols. There are also functions for working with property lists as first-class data structures not attached to particular symbols.

Function: cl-get symbol property &optional default

This function is like get, except that if the property is not found, the default argument provides the return value. (The Emacs Lisp get function always uses nil as the default; this package’s cl-get is equivalent to Common Lisp’s get.)

The cl-get function is setf-able; when used in this fashion, the default argument is allowed but ignored.

Function: cl-remprop symbol property

This function removes the entry for property from the property list of symbol. It returns a true value if the property was indeed found and removed, or nil if there was no such property. (This function was probably omitted from Emacs originally because, since get did not allow a default, it was very difficult to distinguish between a missing property and a property whose value was nil; thus, setting a property to nil was close enough to cl-remprop for most purposes.)

Function: cl-getf place property &optional default

This function scans the list place as if it were a property list, i.e., a list of alternating property names and values. If an even-numbered element of place is found which is eq to property, the following odd-numbered element is returned. Otherwise, default is returned (or nil if no default is given).

In particular,

(get sym prop)  ≡  (cl-getf (symbol-plist sym) prop)

It is valid to use cl-getf as a setf place, in which case its place argument must itself be a valid setf place. The default argument, if any, is ignored in this context. The effect is to change (via setcar) the value cell in the list that corresponds to property, or to cons a new property-value pair onto the list if the property is not yet present.

(put sym prop val) ≡ (setf (cl-getf (symbol-plist sym) prop) val)

The get and cl-get functions are also setf-able. The fact that default is ignored can sometimes be useful:

(cl-incf (cl-get 'foo 'usage-count 0))

Here, symbol foo’s usage-count property is incremented if it exists, or set to 1 (an incremented 0) otherwise.

When not used as a setf form, cl-getf is just a regular function and its place argument can actually be any Lisp expression.

Macro: cl-remf place property

This macro removes the property-value pair for property from the property list stored at place, which is any setf-able place expression. It returns true if the property was found. Note that if property happens to be first on the list, this will effectively do a (setf place (cddr place)), whereas if it occurs later, this simply uses setcdr to splice out the property and value cells.